<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
    <link href="file:///Users/andrew/Downloads/help.css" rel="stylesheet"
          type="text/css"/>
</head>

<body><h1>Jetty Plugin</h1>

<p>The Jetty Plugin runs one or more Jetty server
    instances and can be used to run a web application directly from sources and
    compilation output. </p>

<div id="after-summary"><p>In order to run Jetty on
    a webapp project which is structured according to the usual Quokka defaults
    you don't need to configure anything. Simply type:</p>
<pre>$ quokka jetty:run</pre>
<p>This
    will start Jetty running on port <tt>8080</tt>, serving your project under
    the context name of your project name. Jetty will continue to run until the
    plugin is explicitly stopped, for example, by a <tt>&lt;CTRL&gt;+C</tt>.
    (You can also use the <a href="#stop"><tt>stop</tt></a> target).</p>

<p>It is
    extremely convenient to leave the plugin running because it can be
    configured to periodically scan for changes and automatically redeploy the
    webapp. This makes the development cycle much more productive by eliminating
    the build and deploy steps: you use your IDE to make changes to the project
    and the running web container will automatically pick them up, allowing you
    to test them straight away.</p>

<p>If, for whatever reason, you cannot run on
    an unassembled webapp, the plugin also supports the <tt>run-war</tt> and
    <tt>run-exploded</tt> targets which are discussed below.</p>

<h2>Controlling
    Dependencies</h2>

<p>By default the plugin only includes the minimal
    dependencies for Jetty, allowing you run servlets. If you are using JSP, or
    Jetty Plus functionality you need to add them as options. e.g. to use JSP
    2.1 you would use: </p>
<pre>&lt;plugin group="quokka.plugin.jetty" version="?" paths="(jsp-2.1)"/&gt;</pre>
<p>Available
    options are: jsp-2.0, jsp-2.1, plus, naming, annotations, management. The
    JSP options are mutually exclusive and add JSP 2.0 and 2.1 support
    respectively. For more information on the other options, see the Jetty
    documentation. </p>

<h2>Automatic execution of the plugin</h2>

<p>Sometimes,
    for example when doing integration testing, you'd like to be able to
    automatically have your webapp started at the beginning of the tests, and
    stopped at the end rather than manually executing <tt>quokka jetty:run</tt>
    on the command line.</p>

<p>To do this, you need to set up a couple of
    <tt>&lt;targets&gt;</tt> for the jetty plugin and set the <tt>daemon</tt>
    property to <tt>true</tt> to prevent jetty running indefinitely and force it
    to only execute while quokka is running.</p>

<p>You can bind run and stop
    targets to the lifecycle <tt>initialise-integration-test</tt> and
    <tt>finalise-integration-test</tt> targets like so:</p><pre>&lt;property name="q.jetty.defaults.stopKey" value="foo"/&gt;
&lt;property name="q.jetty.defaults.stopPort" value="9999"/&gt;

&lt;plugin group="quokka.plugin.jetty" version="?"&gt;
    &lt;target name="start-jetty" template="run-template"
            dependency-of="lifecycle:initialise-integration-test"
                  depends="lifecycle:pre-initialise-integration-test"&gt;
        &lt;property name="daemon" value="true"/&gt;
        &lt;property name="scanIntervalSeconds" value="0"/&gt;
    &lt;/target&gt;
    &lt;target name="stop-jetty" template="stop-template"
        dependency-of="lifecycle:finalise-integration-test"
              depends="lifecycle:pre-finalise-integration-test"/&gt;
&lt;/plugin&gt;
</pre>
<p>Note: The above example creates new target instances from the
    templates. Alternatively, you could configure the existing run and stop
    targets.</p>

<h2>Forcing compilation prior to running</h2>

<p>By default, the
    Jetty run targets have no dependencies on other targets. If you prefer
    compilation to always occur prior to running, use the following
    configuration:</p><pre>&lt;plugin group="quokka.plugin.jetty" version="?"&gt;
    &lt;target name="run" depends="compile"/&gt;
&lt;/plugin&gt;
</pre>
<h2>How to stop the plugin from the command line</h2>

<p>The
    <tt>run</tt>, <tt>run-war</tt> and <tt>run-exploded</tt> goals leave the
    plugin running indefinitely. You can terminate it with a
    <tt>&lt;CTRL&gt;+C</tt> in the controlling terminal window, or by executing
    the <tt>stop</tt> goal in another terminal window. If you wish to be able to
    use <tt>quokka jetty:stop</tt> then you need to configure the plugin with a
    special port number and key that you also supply on the <tt>stop</tt>
    command:</p>

<p>Here's an example configuration:</p><pre>&lt;property name="q.jetty.defaults.stopKey" value="foo"/&gt;
&lt;property name="q.jetty.defaults.stopPort" value="9999"/&gt;

&lt;plugin group="quokka.plugin.jetty" version="?"&gt;
</pre>
<p>To start:</p>
<pre>quokka jetty:run</pre>
<p>To stop:</p>
<pre>quokka jetty:stop</pre>
<h2>Properties
    common to run, run-war and run-exploded goals</h2>

<p>The properties are
    divided into those that apply to the container as a whole, and those that
    apply specifically to the webapp:</p>

<h3>Container Configuration</h3>
<ul>
    <li><b>jettyConfig</b> <em>Optional</em>. The location of a jetty.xml
        file that will be applied in addition to any plugin configuration
        parameters. You might use it if you have other webapps, handlers, etc to
        be deployed, or you have other jetty objects that cannot be configured
        from the plugin, such as connectors and security realms.
    </li>

    <li><b>scanIntervalSeconds</b> <em>Optional</em>. The pause in seconds
        between sweeps of the webapp to check for changes and automatically hot
        redeploy if any are detected. By default this is 0, which disables hot
        deployment scanning. A number greater than 0 enables it.
    </li>

    <li><b>scanTargets</b> <em>Optional</em>. A map of resource collections
        that will be scanned for changes and force the reloading of the webapp
        if reloading is set to automatic. Note: these are in <i>addition</i> to
        the standard classes and configuration files.
    </li>

    <li><b>sysProp</b> <em>Optional</em>. A map of system properties. These
        allow you to configure System properties that will be set for the
        execution of the plugin. Existing system properties will not be
        overwritten.
    </li>

    <li><b>port</b> <em>Optional</em>. The port the server will bind to.
        Defaults to 8080.
    </li>

    <li><b>maxIdle</b> <em>Optional</em>. The maximum idle time. Defaults to
        30000.
    </li>

    <li><b>stopPort</b> <em>Optional</em>. The port to listen on for stop
        requests. Must be set together with the stop key to function.
    </li>

    <li><b>stopKey</b> <em>Optional</em>. The key the must be set for a stop
        command to succeed - it is essentially a password to prevent malicious
        shut downs of the server
    </li>

    <li><b>reload</b> <em>Optional</em>. Either <tt>manual</tt> or
        <tt>auto</tt>. If <tt>manual</tt> (the default), the server will reload
        when the enter key is pressed. If <tt>auto</tt> (and
        <tt>scanIntervalSeconds</tt> &gt; <tt>0</tt> and <tt>daemon</tt> is
        <tt>false</tt>), the plugin will scan for changes to the web app classes
        and configuration files and automatically reload the webapp.
    </li>

    <li><b>daemon</b> <em>Optional</em>. Either <tt>true</tt> or
        <tt>false</tt>. If <tt>false</tt> (the default), the server will prevent
        quokka from exiting. Otherwise, it will simply start the server and
        continue. This is useful is some cases such as starting and stopping the
        server automatically for integration tests.
    </li>

    <li><b>extraPaths</b> <em>Optional</em>. Allows additional of extra
        paths to the plugin class loader. This is intended to allow users to add
        additional slf4j logging implementations if they desire. The value
        should be a comma separated list of project paths prefixed with
        "project.". For example, if you defined a project path <tt>logging</tt>
        for the additional libraries, <tt>extraPaths</tt> should be set to
        <tt>project.logging</tt>.
    </li>
</ul>
<h3>Webapp Configuration</h3>
<ul>
    <li><b>contextPath</b> <em>Optional</em>. The context path for your
        webapp. By default, this is set to the project's <tt>war</tt>
        aritifact's <tt>name</tt>. You can override it and set it to anything
        you like here.
    </li>

    <li><b>tempDirectory</b> <em>Optional</em>. The temporary directory to
        use for the webapp. This is set to {<tt>${basedir}/target</tt>} by
        default but can be changed here.
    </li>

    <li><b>overrideDescriptor</b> <em>Optional</em>. A web.xml file which
        will be applied AFTER the webapp's web.xml. This file can be stored
        anywhere. It is used to add or modify the configuration of a web.xml for
        different environments eg test, production etc.
    </li>

    <li><b>defaultsDescriptor</b> <em>Optional</em>. A webdefault.xml file
        to use instead of the supplied jetty default for the webapp.
    </li>

    <li><b>includeInstrumentedOuput</b> <em>Optional</em>. If true, instrumented classes
        will be added to the classpath if instrumentation is enabled so that code
        coverage data can be collected for the web application. Defaults to false.
    </li>
</ul>
</div>
<div id="run"><p>Note: this target depends on
    <tt>lifecycle:compile.</tt> If you do not want this as a dependency, create
    a new instance of the <tt>run-template</tt> instead.</p>

    <p>See <a
            href="#run-template">run-template</a> for configuration options</p></div>
<div id="stop"><p>See <a href="#stop-template">stop-template</a> for
    configuration options</p></div>
<div id="run-exploded"><p>Note: this
    target depends on <tt>jee:war</tt>-exploded. If you do not want this as a
    dependency, create a new instance of the <tt>run-exploded-template</tt>
    instead.</p>

    <p>See <a
            href="#run-exploded-template">run-exploded-template</a> for configuration
        options</p></div>
<div id="run-war"><p>Note: this target depends on
    <tt>jee:war</tt>. If you do not want this as a dependency, create a new
    instance of the <tt>run-war-template</tt> instead.</p>

    <p>See <a
            href="#run-war-template">run-war-template</a> for configuration options</p>
</div>
<div id="run-template"><p><b>Properties:</b></p>
    <ul>
        <li><b>includeTestCompileOutput</b> <i>Optional</i>. If true, the test
            classes will be added to the class path
        </li>

        <li><b>libPath</b> <i>Optional</i>. The id of the path that contains
            dependencies for your web app (that will reside in lib)
        </li>

        <li><b>webApp</b> <i>Optional</i>. The location of the web application
            sources.
        </li>

        <li><b>webXml</b> <i>Optional</i>. The location of the web.xml
            file.
        </li>

        <li><b>jettyEnvXml</b> <em>Optional</em>. it is the location of a
            <tt>jetty-env.xml</tt> file, which allows you to make JNDI bindings that
            will satisfy &lt;env-entry&gt;, &lt;resource-env-ref&gt; and
            &lt;resource-ref&gt; linkages in the <tt>web.xml</tt> that are scoped
            only to the webapp and not shared with other webapps that you may be
            deploying at the same time (e.g. by using a <tt>jettyConfig</tt>
            file).
        </li>
    </ul>
</div>
<div id="run-war-template"><p><b>Properties:</b></p>
    <ul>
        <li><b>webApp</b> The location of the built war file.</li>
    </ul>
</div>
<div id="run-exploded-template"><p></p>

    <p><b>Properties:</b></p>
    <ul>
        <li><b>webApp</b> The location of the exploded war.</li>
    </ul>
</div>
</body>
</html>
